<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Permanent Message Handling</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" />
    <link rel="home" href="index.html" title="Getting Started with Replicated Berkeley DB Applications" />
    <link rel="up" href="repapp.html" title="Chapter 3. The DB Replication Framework" />
    <link rel="previous" href="repmgr_init_example_c.html" title="Adding the Replication Framework to&#10;                    &#10;                    SimpleTxn&#10;            " />
    <link rel="next" href="electiontimes.html" title="Managing Election Times" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Permanent Message Handling</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="repmgr_init_example_c.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 3. The DB Replication Framework</th>
          <td width="20%" align="right"> <a accesskey="n" href="electiontimes.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="fwrkpermmessage"></a>Permanent Message Handling</h2>
          </div>
        </div>
        <div></div>
      </div>
      <p>
               As described in <a href="permmessages.html">Permanent Message Handling</a>,
               messages are marked permanent if they contain database
               modifications that should be committed at the replica.
               DB's replication code decides if it must flush its
               transaction logs to disk depending on whether it receives
               sufficient permanent message acknowledgments from the
               participating replica. More importantly, the thread 
               performing the transaction commit blocks
               until it either receives enough acknowledgments, or the
               acknowledgment timeout expires.
            </p>
      <p>
                The replication framework is fully capable of managing permanent messages
                for you if your application requires it (most do). 
                Almost all of the details of this are handled by the 
                replication framework for you. However, you do have to set some policies
                that tell the replication framework how to handle permanent messages.
            </p>
      <p>
                There are two things that you have to do:
            </p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            <p>
                                    Determine how many acknowledgments
                                    must be received by the master.
                            </p>
          </li>
          <li>
            <p>
                                    Identify the amount of time that
                                    replicas have to send their
                                    acknowledgments.
                            </p>
          </li>
        </ul>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="fmwrkpermpolicy"></a>Identifying Permanent Message Policies</h3>
            </div>
          </div>
          <div></div>
        </div>
        <p>

                        You identify permanent message policies using the
                        

                        <span>
                                <tt class="classname">ReplicationManagerAckPolicy</tt>
                                class which you pass to the environment
                                using the
                                <tt class="methodname">EnvironmentConfig.setReplicationManagerAckPolicy</tt>
                                method.
                        </span>

                        Note that you can set permanent message
                        policies at any time during the life of the
                        application.
                    </p>
        <p>
        The following permanent message policies are available when you use
        the replication framework:
</p>
        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>
                        
                        <tt class="literal">ReplicationManagerAckPolicy.NONE</tt>
                </p>
              <p>
                    No permanent message acknowledgments are required. If
                    this policy is selected, permanent message handling is
                    essentially "turned off." That is, the master will
                    never wait for replica acknowledgments. In this case,
                    transaction log data is either flushed or not strictly
                    depending on the type of commit that is being performed
                    (synchronous or asynchronous).
                </p>
            </li>
            <li>
              <p>
                        
                        <tt class="literal">ReplicationManagerAckPolicy.ONE</tt>
                </p>
              <p>
                    At least one replica must acknowledge the permanent
                    message within the timeout period.  
                </p>
            </li>
            <li>
              <p>
                        
                        <tt class="literal">ReplicationManagerAckPolicy.ONE_PEER</tt>
                </p>
              <p>
                    At least one electable peer must acknowledge the permanent
                    message within the timeout period. 
                    
                    Note that an
                    <span class="emphasis"><em>electable peer</em></span> is simply another
                    environment that can be elected to be a master (that
                    is, it has a priority greater than 0). Do not confuse
                    this with the concept of a peer as used for client to
                    client transfers. See
                    <a href="c2ctransfer.html">Client to Client Transfer</a>
                    for more information on client to client transfers.
                </p>
            </li>
            <li>
              <p>
                    
                    <tt class="literal">ReplicationManagerAckPolicy.ALL</tt>
                </p>
              <p>
                    All environments must acknowledge the message within
                    the timeout period. This
                    policy should be selected only if your replication
                    group has a small number of replicas, and those replicas
                    are on extremely reliable networks and servers.
                </p>
              <p>
                        When this flag is used, the actual number of
                        environments  that must respond is
                        determined by the value set for
                        
                        
                        <span><tt class="methodname">EnvironmentConfig.setReplicationNumSites()</tt>.</span>
                </p>
            </li>
            <li>
              <p>
                    
                    <tt class="literal">ReplicationManagerAckPolicy.ALL_PEERS</tt>
                </p>
              <p>
                        All electable peers must acknowledge the message within the
                    timeout period. This
                    policy should be selected only if your replication
                    group is small, and its various environments
                    are on extremely reliable networks and servers.
                </p>
              <p>
                    Note that an
                    <span class="emphasis"><em>electable peer</em></span> is simply another
                    environment that can be elected to be a master (that
                    is, it has a priority greater than 0). Do not confuse
                    this with the concept of a peer as used for client to
                    client transfers. See
                    <a href="c2ctransfer.html">Client to Client Transfer</a>
                    for more information on client to client transfers.
                </p>
            </li>
            <li>
              <p>
                    
                    <tt class="literal">ReplicationManagerAckPolicy.QUORUM</tt>
                </p>
              <p>
                    A quorum of electable peers must acknowledge the message within the timeout period. 
                    A quorum is reached when acknowledgments are received from the minimum number 
                    of environments needed to ensure that the record remains durable 
                    if an election is held. That is, the master wants to hear from enough 
                    electable replicas that they have committed the record so that if an election 
                    is held, the master knows the record will exist even if a new master is selected.
                </p>
              <p>
                    Note that an
                    <span class="emphasis"><em>electable peer</em></span> is simply another
                    environment that can be elected to be a master (that
                    is, it has a priority greater than 0). Do not confuse
                    this with the concept of a peer as used for client to
                    client transfers. See
                    <a href="c2ctransfer.html">Client to Client Transfer</a>
                    for more information on client to client transfers.
                </p>
            </li>
          </ul>
        </div>
        <p>
        By default, a quorum of sites must must acknowledge a permanent
        message in order for it considered to have been successfully
        transmitted. The actual number of environments that must respond is
        calculated using the value set with
                        
                        
                        <span><tt class="methodname">EnvironmentConfig.setReplicationNumSites()</tt>.</span>
</p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="fmwrkpermtimeout"></a>Setting the Permanent Message Timeout</h3>
            </div>
          </div>
          <div></div>
        </div>
        <p>
                            The permanent message timeout represents the
                            maximum amount of time the committing thread
                            will block waiting for message
                            acknowledgments. If sufficient
                            acknowledgments arrive before this timeout has
                            expired, the thread continues operations as
                            normal. However, if this timeout expires, the
                            committing thread flushes its transaction log
                            buffer before continuing with normal
                            operations.
                    </p>
        <p>
                        You set the timeout value using
                        <tt class="methodname">Environment.setReplicationTimeout()</tt>.
                        You pass this method the 
                        <tt class="methodname">ReplicationTimeoutType.ACK_TIMEOUT</tt>
                        constant and a timeout value in microseconds.
                    </p>
        <p>
                        For example:
                    </p>
        <pre class="programlisting">  dbenv.setReplicationTimeout(ReplicationTimeoutType.ACK_TIMEOUT, 100); </pre>
        <p>
                        This timeout value can be set at anytime during the
                        life of the application. 
                    </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="perm2fmwrkexample"></a>Adding a Permanent Message Policy to 
                            
                            
                            <span>RepQuoteExample</span>
                    </h3>
            </div>
          </div>
          <div></div>
        </div>
        <p>
                        For illustration purposes, we will now update 
                        
                        
                        <tt class="literal">RepQuoteExample</tt>
                        such that it requires only one acknowledgment from
                        a replica on transactional commits. Also, we will give
                        this acknowledgment a 500 microsecond timeout
                        value. This means that our application's main
                        thread will block for up to 500 microseconds waiting
                        for an acknowledgment. If it does not receive at
                        least one acknowledgment in that amount of time,
                        DB will flush the transaction logs to disk
                        before continuing on.
                    </p>
        <p>
                        This is a very simple update. We can perform the
                        entire thing in 
                        
                        <tt class="methodname">RepQuoteExample.init()</tt>
                        immediately after we set the application's priority
                        and before we open our environment handle.
                    </p>
        <pre class="programlisting">    public int init(RepConfig config)
        throws DatabaseException
    {
        int ret = 0;
        appConfig = config;
        EnvironmentConfig envConfig = new EnvironmentConfig();
        envConfig.setErrorStream(System.err);
        envConfig.setErrorPrefix(RepConfig.progname);

        envConfig.setReplicationManagerLocalSite(appConfig.getThisHost());
        for (ReplicationHostAddress host = appConfig.getFirstOtherHost();
            host != null; host = appConfig.getNextOtherHost())
        {
            envConfig.replicationManagerAddRemoteSite(host);
        }

        if (appConfig.totalSites &gt; 0)
            envConfig.setReplicationNumSites(appConfig.totalSites);
        envConfig.setReplicationPriority(appConfig.priority);

        <b class="userinput"><tt>envConfig.setReplicationManagerAckPolicy(
                ReplicationManagerAckPolicy.ALL);
        envConfig.setReplicationTimeout(ReplicationTimeoutType.ACK_TIMEOUT,
                500); </tt></b>

        envConfig.setCacheSize(RepConfig.CACHESIZE);
        envConfig.setTxnNoSync(true);
    ... </pre>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="repmgr_init_example_c.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="repapp.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="electiontimes.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Adding the Replication Framework to
                    
                    SimpleTxn
             </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Managing Election Times</td>
        </tr>
      </table>
    </div>
  </body>
</html>
